<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Using Zend_Tool On The Command Line - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.tool.usage.cli.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.tool.usage.cli.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.tool.html">Zend_Tool</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.tool.html">Zend_Tool</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.tool.extending.html">Extending Zend_Tool</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.tool.usage.cli" class="section"><div class="info"><h1 class="title">Using Zend_Tool On The Command Line</h1></div>
    

    <p class="para">
        The <acronym class="acronym">CLI</acronym>, or command line tool (internally known as the console tool),
        is currently the primary interface for dispatching <span class="classname">Zend_Tool</span>
        requests. With the <acronym class="acronym">CLI</acronym> tool, developers can issue tooling requests
        inside the &quot;command line window&quot;, also commonly known as a &quot;terminal&quot; window. This
        environment is predominant in the *nix environment, but also has a common implementation
        in windows with the <var class="filename">cmd.exe</var>, console2 and also with the Cygwin project.
    </p>

    

    <div class="section" id="zend.tool.usage.cli.installation"><div class="info"><h1 class="title">Installation</h1></div>
        

        <div class="section" id="zend.tool.usage.cli.installation.download-and-go"><div class="info"><h1 class="title">Download And Go</h1></div>
            

            <p class="para">
                First download Zend Framework. This can be done by going to framework.zend.com
                and downloading the latest release. After you&#039;ve downloaded the package and placed
                it on your system. The next step is to make the zf command available to your
                system. The easiest way to do this, is to copy the proper files from the bin/
                directory of the download, and place these files within the
                <em class="emphasis">same</em> directory as the location of the <acronym class="acronym">PHP</acronym>
                cli binary.
            </p>
        </div>

        <div class="section" id="zend.tool.usage.cli.installation.pear"><div class="info"><h1 class="title">Installing Via Pear</h1></div>
            

            <p class="para">
                To install via PEAR, you must use the 3rd party zfcampus.org site to retrieve the
                latest Zend Framework PEAR package. These packages are typically built within a day
                of an official Zend Framework release. The benefit of installing via the PEAR
                package manager is that during the install process, the ZF library will end up on
                the include_path, and the zf.php and zf scripts will end up in a place on your
                system that will allow you to run them without any additional setup.
            </p>

            <pre class="programlisting brush: text">
pear channel-discover pear.zfcampus.org
pear install zfcampus/zf
</pre>


            <p class="para">
                That is it. After the initial install, you should be able to continue on by
                running the zf command. Go good way to check to see if it&#039;t there is to run
                zf --help
            </p>
        </div>

        <div class="section" id="zend.tool.usage.cli.installation.install-by-hand"><div class="info"><h1 class="title">Installing by Hand</h1></div>
            

            <p class="para">
                Installing by hand refers to the process of forcing the zf.php and Zend Framework
                library to work together when they are placed in non-convential places, or at least,
                in a place that your system cannot dispatch from easily (typical of programs in your
                system PATH).
            </p>

            <p class="para">
                If you are on a *nix or mac system, you can also create a link from somewhere in
                your path to the zf.sh file. If you do this, you do not need to worry about having
                Zend Framework&#039;s library on your include_path, as the zf.php and zf.sh files will
                be able to access the library relative to where they are (meaning the ./bin/ files
                are ../library/ relative to the Zend Framework library).
            </p>

            <p class="para">
                There are a number of other options available for setting up the zf.php and library
                on your system. These options revolve around setting specific environment
                variables. These are described in the later section on &quot;customizing the CLI
                environement&quot;. The environment variables for setting the zf.php include_path,
                ZEND_TOOL_INCLUDE_PATH and ZF_TOOL_INCLUDE_PATH_PREPEND, are the ones of most interest.
            </p>
        </div>
    </div>

    <div class="section" id="zend.tool.usage.cli.general-purpose-commands"><div class="info"><h1 class="title">General Purpose Commands</h1></div>
        

        <div class="section" id="zend.tool.usage.cli.general-purpose-commands.version"><div class="info"><h1 class="title">Version</h1></div>
            

            <p class="para">
                This will show the current version number of the copy of Zend Framework the zf.php
                tool is using.
            </p>

            <pre class="programlisting brush: text">
zf show version
</pre>

        </div>

        <div class="section" id="zend.tool.usage.cli.general-purpose-commands.built-in-help"><div class="info"><h1 class="title">Built-in Help</h1></div>
            

            <p class="para">
                The built-in help system is the primary place where you can get up-to-date
                information on what your system is capable of doing. The help system is dynamic in
                that as providers are added to your system, they are automatically dispatchable, and
                as such, the parameters required to run them will be in the help screen. The
                easiest way to retrieve the help screen is the following:
            </p>

            <pre class="programlisting brush: text">
zf --help
</pre>


            <p class="para">
                This will give you an overview of the various capabilities of the system.
                Sometimes, there are more finite commands than can be run, and to gain more
                information about these, you might have to run a more specialized help command.
                For specialized help, simply replace any of the elements of the command with a &quot;?&quot;.
                This will tell the help system that you want more information about what commands
                can go in place of the question mark. For example:
            </p>

            <pre class="programlisting brush: text">
zf ? controller
</pre>


            <p class="para">
                The above means &quot;show me all &#039;actions&#039; for the provider &#039;controller&#039;&quot;; while the
                following:
            </p>

            <pre class="programlisting brush: text">
zf show ?
</pre>


            <p class="para">
                means &quot;show me all providers that support the &#039;show&#039; action&quot;. This works for
                drilling down into options as well as you can see in the following examples:
            </p>

            <pre class="programlisting brush: text">
zf show version.? (show any specialties)
zf show version ? (show any options)
</pre>

        </div>

        <div class="section" id="zend.tool.usage.cli.general-purpose-commands.manifest"><div class="info"><h1 class="title">Manifest</h1></div>
            

            <p class="para">
                This will show what information is in the tooling systems manifest. This is more
                important for provider developers than casual users of the tooling system.
            </p>

            <pre class="programlisting brush: text">
zf show manifest
</pre>

        </div>

        
    </div>

    <div class="section" id="zend.tool.usage.cli.project-specific-commands"><div class="info"><h1 class="title">Project Specific Commands</h1></div>
        

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.project"><div class="info"><h1 class="title">Project</h1></div>
            

            <p class="para">
                The project provider is the first command you might want to run. This will setup the
                basic structure of your application. This is required before any of the other
                providers can be executed.
            </p>

            <pre class="programlisting brush: text">
zf create project MyProjectName
</pre>


            <p class="para">
                This will create a project in a directory called ./MyProjectName. From this point
                on, it is important to note that any subsequent commands on the command line must be
                issued from within the project directory you had just created. So, after creation,
                changing into that directory is required.
            </p>
        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.module"><div class="info"><h1 class="title">Module</h1></div>
            

            <p class="para">
                The module provider allows for the easy creation of a Zend Framework module. A
                module follows the hMVC pattern loosely. When creating modules, it will take the
                same structure used at the application/ level, and duplicate it inside of the chosen
                name for your module, inside of the &quot;modules&quot; directory of the application/
                directory without duplicating the modules directory itself. For example:
            </p>

            <pre class="programlisting brush: text">
zf create module Blog
</pre>


            <p class="para">
                This will create a module named Blog at application/modules/Blog, and all of the
                artifacts that a module will need.
            </p>
        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.controller"><div class="info"><h1 class="title">Controller</h1></div>
            

            <p class="para">
                The controller provider is responsible for creating (mostly) empty controllers as
                well as their corresponding view script directories and files. To utilize it to
                create an &#039;Auth&#039; controlller, for example, execute:
            </p>

            <pre class="programlisting brush: text">
zf create controller Auth
</pre>


            <p class="para">
                This will create a controller named Auth, specifically it will create a file at
                application/controllers/AuthController.php with the AuthController inside.
                If you wish to create a controller for a module, use any of the following:
            </p>

            <pre class="programlisting brush: text">
zf create controller Post 1 Blog
zf create controller Post -m Blog
zf create controller Post --module=Blog
</pre>


            <p class="para">
                Note: In the first command, 1 is the value for the &quot;includeIndexAction&quot; flag.
            </p>
        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.action"><div class="info"><h1 class="title">Action</h1></div>
            

            <p class="para">
                To create an action within an existing controller:
            </p>

            <pre class="programlisting brush: text">
zf create action login Auth
zf create action login -c Auth
zf create action login --controller-name=Auth
</pre>

        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.view"><div class="info"><h1 class="title">View</h1></div>
            

            <p class="para">
                To create a view outside of the normal controller/action creation, you would use
                one of the following:
            </p>

            <pre class="programlisting brush: text">
zf create view Auth my-script-name
zf create view -c Auth -a my-script-name
            </pre>


            <p class="para">
                This will create a view script in the controller folder of Auth.
            </p>
        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.model"><div class="info"><h1 class="title">Model</h1></div>
            

            <p class="para">
                The model provider is only responsible for creating the proper model files,
                with the proper name inside the application folder. For example
            </p>

            <pre class="programlisting brush: text">
zf create model User
</pre>


            <p class="para">
                If you wish to create a model within a specific module:
            </p>

            <pre class="programlisting brush: text">
zf create model Post -m Blog
</pre>


            <p class="para">
                The above will create a &#039;Post&#039; model inside of the &#039;Blog&#039; module.
            </p>
        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.form"><div class="info"><h1 class="title">Form</h1></div>
            

            <p class="para">
                The form provider is only responsible for creating the proper form file and
                init() method, with the proper name inside the application folder. For example:
            </p>

            <pre class="programlisting brush: text">
zf create form Auth
</pre>


            <p class="para">
                If you wish to create a model within a specific module:
            </p>

            <pre class="programlisting brush: text">
zf create form Comment -m Blog
</pre>


            <p class="para">
                The above will create a &#039;Comment&#039; form inside of the &#039;Blog&#039; module.
            </p>
        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.database-adapter"><div class="info"><h1 class="title">DbAdapter</h1></div>
            

            <p class="para">
                To configure a DbAdapter, you will need to provide the information as a url
                encoded string. This string needs to be in quotes on the command line.
            </p>

            <p class="para">
                For example, to enter the following information:

                <ul class="itemizedlist">
                    <li class="listitem">
                        <p class="para">adapter: Pdo_Mysql</p>
                    </li>

                    <li class="listitem">
                        <p class="para">username: test</p>
                    </li>

                    <li class="listitem">
                        <p class="para">password: test</p>
                    </li>

                    <li class="listitem">
                        <p class="para">dbname: test </p>
                    </li>
                </ul>

                The following will have to be run on the command line:
            </p>

            <pre class="programlisting brush: text">
zf configure dbadapter &quot;adapter=Pdo_Mysql&amp;username=test&amp;password=test&amp;dbname=test&quot;
</pre>


            <p class="para">
                This assumes you wish to store this information inside of the
                &#039;production&#039; space of the application configuration file. The following will
                demonstrate an sqlite configuration, in the &#039;development&#039; section of the
                application config file.
            </p>

            <pre class="programlisting brush: text">
zf configure dbadapter &quot;adapter=Pdo_Sqlite&amp;dbname=../data/test.db&quot; development
zf configure dbadapter &quot;adapter=Pdo_Sqlite&amp;dbname=../data/test.db&quot; -s development
</pre>

        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.db-table"><div class="info"><h1 class="title">DbTable</h1></div>
            

            <p class="para">
                The DbTable provider is responsible for creating
                <span class="classname">Zend_Db_Table</span> model/data access files for your application to
                consume, with the proper class name, and in the proper location in the application.
                The two important pieces of information are the <em class="emphasis">DbTable name</em>,
                and the <em class="emphasis">actual database table name</em>. For example:
            </p>

            <pre class="programlisting brush: text">
zf create dbtable User user
zf create dbtable User -a user

// also accepts a force option to overwrite existing files
zf create dbtable User user -f
zf create dbtable User user --force-overwrite
</pre>


            <p class="para">
                The DbTable provider is also capable of creating the proper files by
                scanning the database configured with the above DbAdapter provider.
            </p>

            <pre class="programlisting brush: text">
zf create dbtable.from-database
</pre>


            <p class="para">
                When executing the above, it might make sense to use the pretend / &quot;-p&quot;
                flag first so that you can see what would be done, and what tables can
                be found in the database.
            </p>

            <pre class="programlisting brush: text">
zf -p create dbtable.from-database
</pre>

        </div>

        <div class="section" id="zend.tool.usage.cli.project-specific-commands.layout"><div class="info"><h1 class="title">Layout</h1></div>
            

            <p class="para">
                Currently, the only supported action for layouts is simply to enable them
                will setup the proper keys in the application.ini file for the application
                resource to work, and create the proper directories and layout.phtml file.
            </p>

            <pre class="programlisting brush: text">
zf enable layout
</pre>

        </div>
    </div>

    <div class="section" id="zend.tool.usage.cli.environment-customization"><div class="info"><h1 class="title">Environment Customization</h1></div>
        

        <div class="section" id="zend.tool.usage.cli.environment-customization.storage-directory"><div class="info"><h1 class="title">The Storage Directory</h1></div>
            

            <p class="para">
                The storage directory is important so that providers may have a place to find
                custom user generated logic that might change the way they behave. One example
                can be found below is the placement of a custom project profile file.
            </p>

            <pre class="programlisting brush: text">
zf --setup storage-directory
</pre>

        </div>

        <div class="section" id="zend.tool.usage.cli.environment-customization.configuration-file"><div class="info"><h1 class="title">The Configuration File</h1></div>
            

            <p class="para">
                This will create the proper zf.ini file. This <em class="emphasis">should</em>
                be run after <strong class="command">zf --setup storage-directory</strong>. If it is not, it will
                be located inside the users home directory. If it is, it will be located inside
                the users storage directory.
            </p>

            <pre class="programlisting brush: text">
zf --setup config-file
</pre>

        </div>

        <div class="section" id="zend.tool.usage.cli.environment-customization.environment-locations"><div class="info"><h1 class="title">Environment Locations</h1></div>
            

            <p class="para">
                These should be set if you wish to override the default places where zf will
                attempt to read their values.
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">ZF_HOME</p>

                    <ul class="itemizedlist">
                        <li class="listitem">
                            <p class="para">the directory this tool will look for a home directory</p>
                        </li>

                        <li class="listitem"><p class="para">directory must exist</p></li>

                        <li class="listitem">
                            <p class="para">search order:</p>

                            <ul class="itemizedlist">
                                <li class="listitem"><p class="para">ZF_HOME environment variable</p></li>
                                <li class="listitem"><p class="para">HOME environment variable</p></li>
                                <li class="listitem"><p class="para">then HOMEPATH environment variable</p></li>
                            </ul>
                        </li>
                    </ul>
                </li>

                <li class="listitem">
                    <p class="para">ZF_STORAGE_DIRECTORY</p>

                    <ul class="itemizedlist">
                        <li class="listitem">
                            <p class="para">where this tool will look for a storage directory</p>
                        </li>

                        <li class="listitem"><p class="para">directory must exist</p></li>

                        <li class="listitem">
                            <p class="para">search order:</p>

                            <ul class="itemizedlist">
                                <li class="listitem">
                                    <p class="para">ZF_STORAGE_DIRECTORY environment variable</p>
                                </li>

                                <li class="listitem"><p class="para">$homeDirectory/.zf/ directory</p></li>
                            </ul>
                        </li>
                    </ul>
                </li>

                <li class="listitem">
                    <p class="para">ZF_CONFIG_FILE</p>

                    <ul class="itemizedlist">
                        <li class="listitem">
                            <p class="para">where this tool will look for a configuration file</p>
                        </li>

                        <li class="listitem">
                            <p class="para">search order:</p>

                            <ul class="itemizedlist">
                                <li class="listitem">
                                    <p class="para">ZF_CONFIG_FILE environment variable</p>
                                </li>

                                <li class="listitem">
                                    <p class="para">$homeDirectory/.zf.ini file if it exists</p>
                                </li>

                                <li class="listitem">
                                    <p class="para">$storageDirectory/zf.ini file if it exists</p>
                                </li>
                            </ul>
                        </li>
                    </ul>
                </li>

                <li class="listitem">
                    <p class="para">ZEND_TOOL_INCLUDE_PATH</p>

                    <ul class="itemizedlist">
                        <li class="listitem">
                            <p class="para">set the include_path for this tool to use this value</p>
                        </li>

                        <li class="listitem">
                            <p class="para">original behavior:</p>

                            <ul class="itemizedlist">
                                <li class="listitem">
                                    <p class="para">
                                        use <acronym class="acronym">PHP</acronym>&#039;s include_path to find ZF
                                    </p>
                                </li>

                                <li class="listitem">
                                    <p class="para">use the ZEND_TOOL_INCLUDE_PATH environment variable</p>
                                </li>

                                <li class="listitem">
                                    <p class="para">
                                        use the path ../library (relative to zf.php) to find ZF
                                    </p>
                                </li>
                            </ul>
                        </li>
                    </ul>
                </li>

                <li class="listitem">
                    <p class="para">ZF_TOOL_INCLUDE_PATH_PREPEND</p>

                    <ul class="itemizedlist">
                        <li class="listitem">
                            <p class="para">prepend the current php.ini include_path with this value</p>
                        </li>
                    </ul>
                </li>
            </ul>
        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.tool.html">Zend_Tool</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.tool.html">Zend_Tool</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.tool.extending.html">Extending Zend_Tool</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.tool.html">Zend_Tool</a></li>
  <li class="active"><a href="zend.tool.usage.cli.html">Using Zend_Tool On The Command Line</a></li>
  <li><a href="zend.tool.extending.html">Extending Zend_Tool</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>